From bcd650f169a587309b49fec830acd5dd96c4616f Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 16 Jul 2020 21:48:08 -0400 Subject: [PATCH] docs: Revise the filter docs a bit --- gtk/gtkcustomfilter.c | 14 +++++++++----- gtk/gtkfilter.c | 25 +++++++++++++------------ gtk/gtkfilterlistmodel.c | 14 ++++++++++---- gtk/gtkmultifilter.c | 6 +++--- gtk/gtkstringfilter.c | 2 +- 5 files changed, 36 insertions(+), 25 deletions(-) diff --git a/gtk/gtkcustomfilter.c b/gtk/gtkcustomfilter.c index d2ec8dc23a..13bcf86342 100644 --- a/gtk/gtkcustomfilter.c +++ b/gtk/gtkcustomfilter.c @@ -29,8 +29,8 @@ * @Title: GtkCustomFilter * @Short_description: Filtering with callbacks * - * #GtkCustomFilter is a #GtkFilter that uses a callback to determine whether - * to include an item or not. + * #GtkCustomFilter is a #GtkFilter that uses a callback to determine + * whether to include an item or not. */ struct _GtkCustomFilter { @@ -98,11 +98,13 @@ gtk_custom_filter_init (GtkCustomFilter *self) * gtk_custom_filter_new: * @match_func: (nullable): function to filter items * @user_data: (nullable): user data to pass to @match_func - * @user_destroy: destory notify + * @user_destroy: destroy notify for @user_data * * Creates a new filter using the given @match_func to filter * items. * + * If @match_func is %NULL, the filter matches all items. + * * If the filter func changes its filtering behavior, * gtk_filter_changed() needs to be called. * @@ -127,10 +129,12 @@ gtk_custom_filter_new (GtkCustomFilterFunc match_func, * @self: a #GtkCustomFilter * @match_func: (nullable): function to filter items * @user_data: (nullable): user data to pass to @match_func - * @user_destroy: destory notify + * @user_destroy: destroy notify for @user_data * * Sets (or unsets) the function used for filtering items. - * + * + * If @match_func is %NULL, the filter matches all items. + * * If the filter func changes its filtering behavior, * gtk_filter_changed() needs to be called. * diff --git a/gtk/gtkfilter.c b/gtk/gtkfilter.c index 697359d74b..fc3d63efaf 100644 --- a/gtk/gtkfilter.c +++ b/gtk/gtkfilter.c @@ -30,20 +30,21 @@ * @Short_description: Filtering items * @See_also: #GtkFilerListModel * - * #GtkFilter is the way to describe filters to be used in #GtkFilterListModel. - * - * The model will use a filter to determine if it should filter items or not - * by calling gtk_filter_match() for each item and only keeping the ones - * visible that the function returns %TRUE for. + * A #GtkFilter object describes the filtering to be performed by a + * #GtkFilterListModel. + * + * The model will use the filter to determine if it should include items + * or not by calling gtk_filter_match() for each item and only keeping the + * ones that the function returns %TRUE for. * * Filters may change what items they match through their lifetime. In that - * case, they can call gtk_filter_changed() which will emit the #GtkFilter:changed - * signal to notify that previous filter results are no longer valid and that - * items should be checked via gtk_filter_match() again. + * case, they will emit the #GtkFilter:changed signal to notify that previous + * filter results are no longer valid and that items should be checked again + * via gtk_filter_match(). * - * GTK provides various premade filter implementations for common filtering + * GTK provides various pre-made filter implementations for common filtering * operations. These filters often include properties that can be linked to - * various widgets to easily allow searches. + * various widgets to easily allow searches. * * However, in particular for large lists or complex search methods, it is * also possible to subclass #GtkFilter and provide one's own filter. @@ -118,7 +119,7 @@ gtk_filter_init (GtkFilter *self) * @self: a #GtkFilter * @item: (type GObject) (transfer none): The item to check * - * Checks if the given @item is matched by the filter or not. + * Checks if the given @item is matched by the filter or not. * * Returns: %TRUE if the filter matches the item and a filter model should * keep it, %FALSE if not. @@ -140,7 +141,7 @@ gtk_filter_match (GtkFilter *self, * Gets the known strictness of @filters. If the strictness is not known, * %GTK_FILTER_MATCH_SOME is returned. * - * This value may change after emission of the GtkFilter:changed signal. + * This value may change after emission of the #GtkFilter:changed signal. * * This function is meant purely for optimization purposes, filters can * choose to omit implementing it, but #GtkFilterListModel uses it. diff --git a/gtk/gtkfilterlistmodel.c b/gtk/gtkfilterlistmodel.c index 387393cd69..a02ad57abf 100644 --- a/gtk/gtkfilterlistmodel.c +++ b/gtk/gtkfilterlistmodel.c @@ -771,8 +771,8 @@ gtk_filter_list_model_get_model (GtkFilterListModel *self) * @self: a #GtkFilterListModel * @incremental: %TRUE to enable incremental filtering * - * When incremental filtering is enabled, the filterlistmodel will not run - * filters immediately, but will instead queue an idle handler that + * When incremental filtering is enabled, the GtkFilterListModel will not + * run filters immediately, but will instead queue an idle handler that * incrementally filters the items and adds them to the list. This of course * means that items are not instantly added to the list, but only appear * incrementally. @@ -837,8 +837,14 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self) * * You can use this value to check if @self is busy filtering by * comparing the return value to 0 or you can compute the percentage - * of the filter remaining by dividing the return value by - * g_list_model_get_n_items(gtk_filter_list_model_get_model (self)). + * of the filter remaining by dividing the return value by the total + * number of items in the underlying model: + * + * |[ + * pending = gtk_filter_list_model_get_pending (self); + * model = gtk_filter_list_model_get_model (self); + * percentage = pending / (double) g_list_model_get_n_items (model); + * ]| * * Returns: The number of items not yet filtered **/ diff --git a/gtk/gtkmultifilter.c b/gtk/gtkmultifilter.c index 6fb08cc9da..8c8ac9c068 100644 --- a/gtk/gtkmultifilter.c +++ b/gtk/gtkmultifilter.c @@ -35,10 +35,10 @@ * GtkMultiFilter is the base type that implements support for handling * multiple filters. * - * GtkAnyFilter is an implementation of GtkMultiFilter that matches an item + * GtkAnyFilter is a subclass of GtkMultiFilter that matches an item * when at least one of its filters matches. * - * GtkEveryFilter is an implementation of GtkMultiFilter that matches an item + * GtkEveryFilter is a subclass of GtkMultiFilter that matches an item * when each of its filters matches. */ struct _GtkMultiFilter @@ -413,7 +413,7 @@ gtk_every_filter_init (GtkEveryFilter *self) /** * gtk_every_filter_new: * - * Creates a new empty "every" filter. + * Creates a new empty "every" filter. * Use gtk_multi_filter_append() to add filters to it. * * This filter matches an item if each of the filters added to it diff --git a/gtk/gtkstringfilter.c b/gtk/gtkstringfilter.c index df45fe4f2a..2aed620f50 100644 --- a/gtk/gtkstringfilter.c +++ b/gtk/gtkstringfilter.c @@ -27,7 +27,7 @@ /** * SECTION:gtkstringfilter * @Title: GtkStringFilter - * @Short_description: Filtering by string + * @Short_description: Filtering by strings * * GtkStringFilter determines whether to include items by looking * at strings and comparing them to a fixed search term. The strings -- 2.30.2